home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac: Not for Sale / Another.not.for.sale (Australia).iso / hold me in your arms / PGP 2.6 / rsaref Toolkit / doc / rsaref.txt < prev    next >
Text File  |  1992-03-03  |  30KB  |  807 lines

  1.                              RSAREF(TM):
  2.           A Cryptographic Toolkit for Privacy-Enhanced Mail
  3.                        Library Reference Manual
  4.  
  5.                            RSA Laboratories
  6.                             March 2, 1992
  7.  
  8.     Copyright (C) 1991-2 RSA Laboratories, a division of RSA Data
  9.                  Security, Inc. All rights reserved.
  10.  
  11.  
  12. INTRODUCTION
  13.  
  14. This manual is a reference guide for users of RSAREF, a cryptographic
  15. toolkit designed to facilitate rapid development of Internet
  16. Privacy-Enhanced Mail (PEM) [1-3] implementations.
  17.  
  18. RSAREF supports the following PEM-specified algorithms:
  19.  
  20.      -    RSA encryption and key generation, as defined by RSA Data
  21.             Security's Public-Key Cryptography Standards (PKCS) [4]
  22.      -    MD2 and MD5 message digests [3,5,6]
  23.      -    DES (Data Encryption Standard) in cipher-block chaining mode
  24.             [7,8]
  25.  
  26. RSAREF is written entirely in C. Its application interface includes
  27. the following routines:
  28.  
  29.       R_SignPEMBlock     computes a digital signature on a message
  30. R_VerifyPEMSignature     verifies a digital signature on a message
  31. R_VerifyBlockSignature   verifies a digital signature on a block of
  32.                            data such as a certificate
  33.  
  34.       R_SealPEMBlock     computes a digital signature and encrypts a
  35.                            message
  36.       R_OpenPEMBlock     decrypts an encrypted message and verifies a
  37.                            digital signature
  38.  
  39.        R_DigestBlock     computes a message digest on a message
  40.  
  41.    R_GeneratePEMKeys     generates an RSA public/private key pair
  42.  
  43.         R_RandomInit     initializes a random structure
  44.       R_RandomUpdate     mixes bytes into a random structure
  45. R_GetRandomBytesNeeded   computes the number of mix-in bytes still
  46.                            needed to seed a random structure
  47.        R_RandomFinal     zeroizes a random structure
  48.  
  49. A simple PEM implementation can be built directly on top of these
  50. routines, together with message parsing and formatting routines and
  51. certificate-management routines.
  52.  
  53. This manual is divided into five main parts and three appendices.
  54.  
  55. This part introduces RSAREF. The next three parts explain RSAREF
  56. procedures: random structures; cryptographic enhancements; and
  57. key-pair generation. The last part documents the platform-specific
  58. run-time library.
  59.  
  60. Appendix A lists RSAREF error types. Appendix B lists RSAREF types
  61. and constants. Appendix C lists platform-specific types and
  62. constants.
  63.  
  64. RSAREF is intended to be compatible with forthcoming revised versions
  65. of the PEM RFCs, which are now in the unofficial "Internet-Draft"
  66. stage.
  67.  
  68.  
  69. RANDOM STRUCTURES
  70.  
  71. A random structure contains a seed from which a pseudorandom sequence
  72. of bytes is derived. RSAREF generates keys and pads RSA encryption
  73. blocks with bytes derived from a random structure.
  74.  
  75. Random structures are used by both message-processing and
  76. key-generation applications.
  77.  
  78. RSAREF initializes a random structure with the procedure
  79. R_RandomInit. A typical application calls R_RandomInit on entry.
  80.  
  81. A new random structure is not ready for use until it is seeded by
  82. mixing in some random bytes. RSAREF seeds a random structure with the
  83. procedure R_RandomUpdate and R_GetRandomBytesNeeded. A random
  84. structure is considered seeded when the number of bytes still needed
  85. reaches zero. More bytes can be mixed in after the random structure
  86. is seeded. A typical application calls R_GetRandomBytesNeeded and
  87. R_RandomUpdate immediately after calling R_RandomInit.
  88.  
  89. RSAREF zeroizes a random structure with the procedure R_RandomFinal.
  90. A typical application calls R_RandomFinal on exit.
  91.  
  92.  
  93. R_RandomInit
  94.  
  95. int R_RandomInit (
  96.   R_RANDOM_STRUCT *randomStruct             /* new random structure */
  97. );
  98.  
  99. R_RandomInit initializes a new random structure, storing the result
  100. in randomStruct.
  101.  
  102. Return value:       0    success
  103.               nonzero    reserved for future compatibility
  104.  
  105.  
  106. R_RandomUpdate
  107.  
  108. int R_RandomUpdate (
  109.   R_RANDOM_STRUCT *randomStruct,                /* random structure */
  110.   unsigned char *block,                /* block of values to mix in */
  111.   unsigned int blockLen                          /* length of block */
  112. );
  113.  
  114. R_RandomUpdate mixes blockLen bytes from block into randomStruct.
  115.  
  116. Return value:       0    success
  117.               nonzero    reserved for future compatibility
  118.  
  119.  
  120. R_GetRandomBytesNeeded
  121.  
  122. int R_GetRandomBytesNeeded (
  123.   unsigned int *bytesNeeded,       /* number of mix-in bytes needed */
  124.   R_RANDOM_STRUCT *randomStruct                 /* random structure */
  125. );
  126.  
  127. R_GetRandomBytesNeeded computes the number of mix-in bytes still
  128. needed to seed randomStruct, storing the result in bytesNeeded.
  129.  
  130. Return value:       0    success
  131.               nonzero    reserved for future compatibility
  132.  
  133.  
  134. R_RandomFinal
  135.  
  136. void R_RandomFinal (
  137.   R_RANDOM_STRUCT *randomStruct                 /* random structure */
  138. );
  139.  
  140. R_RandomFinal zeroizes randomStruct.
  141.  
  142. No return value.
  143.  
  144.  
  145. CRYPTOGRAPHIC ENHANCEMENTS
  146.  
  147. RSAREF applies cryptographic enhancements to messages with six
  148. procedures: R_SignPEMBlock, R_VerifyPEMSignature,
  149. R_VerifyBlockSignature, R_SealPEMBlock, R_OpenPEMBlock, and
  150. R_DigestBlock.
  151.  
  152. The first five procedures are typically called by message-processing
  153. applications. R_DigestBlock is typically called by key-generation
  154. applications when computing the message digest of a prototype
  155. certificate [2,9].
  156.  
  157. To sign a message, an application calls R_SignPEMBlock, giving these
  158. arguments:
  159.  
  160.   -  a pointer to the message content, and the message length
  161.   -  an integer identifying which message-digest algorithm to apply
  162.        (MD2 or MD5)
  163.   -  a flag indicating whether to encode the message in printable
  164.        ASCII according to RFC 1113
  165.   -  the signer's RSA private key
  166.  
  167. R_SignPEMBlock signs the message with the signer's private key and
  168. the specified message-digest algorithm, and optionally encodes the
  169. message in printable ASCII. It returns the signature, possibly the
  170. encoded message, and the status of the operation. The signature is
  171. encoded according to RFC 1113.
  172.  
  173. To verify a signature on a message, an application calls
  174. R_VerifyPEMSignature, giving these arguments:
  175.  
  176.   -  a pointer to the (possibly encoded) message, and the message
  177.        length
  178.   -  a pointer to the signature, and the signature length
  179.   -  an integer identifying which message-digest algorithm was applied
  180.        (MD2 or MD5)
  181.   -  a flag indicating whether the message was encoded in printable
  182.        ASCII
  183.   -  the signer's RSA public key
  184.  
  185. R_VerifyPEMSignature decodes the message if it was encoded and
  186. verifies the signature on the message with the signer's public key
  187. and the specified message-digest algorithm. It returns the message
  188. content if the message was encoded, and the status of the operation.
  189.  
  190. To verify a signature on a block of data such as a certificate where
  191. the signature is not encoded in printable ASCII, an application calls
  192. R_VerifyBlockSignature, giving these arguments:
  193.  
  194.   -  a pointer to the block, and the block length
  195.   -  a pointer to the signature, and the signature length
  196.   -  an integer identifying which message-digest algorithm was applied
  197.        (MD2 or MD5)
  198.   -  the signer's RSA public key
  199.  
  200. R_VerifyBlockSignature verifies the signature on the message with the
  201. signer's public key and the specified message-digest algorithm. It
  202. returns the status of the operation.
  203.  
  204. To seal a message (sign and encrypt it), an application calls
  205. R_SealPEMBlock, giving these arguments:
  206.  
  207.   -  a pointer to the message content, and the message length
  208.   -  an integer identifying which message-digest algorithm to apply
  209.        (MD2 or MD5)
  210.   -  the signer's RSA private key
  211.   -  the recipient's RSA public key
  212.  
  213. R_SealPEMBlock signs the message with the signer's private key and
  214. the specified message-digest algorithm, encrypts the message and the
  215. signature with a random DES key, and encrypts the DES key with the
  216. recipient's public key. It returns the encrypted message, the
  217. encrypted key, the encrypted signature, the DES initialization
  218. vector, and the status of the operation. The encrypted message, key,
  219. and signature are encoded according to RFC 1113. 
  220.  
  221. To open a message (decrypt it and verify its signature), an
  222. application calls R_OpenPEMBlock, giving these arguments:
  223.  
  224.   -  a pointer to the encrypted message, and the encrypted message
  225.        length
  226.   -  a pointer to the encrypted key, and the encrypted key length
  227.   -  a pointer to the encrypted signature, and the encrypted signature
  228.        length
  229.   -  a DES initialization vector
  230.   -  an integer identifying which message-digest algorithm was applied
  231.        (MD2 or MD5)
  232.   -  the signer's RSA public key
  233.   -  the recipient's RSA private key
  234.  
  235. R_OpenPEMBlock decrypts the encrypted DES key with the recipient's
  236. private key, decrypts the encrypted message and the encrypted
  237. signature with the DES key, and verifies the signature on the message
  238. with the signer's public key and the specified message-digest
  239. algorithm. It returns the message content and the status of the
  240. operation.
  241.  
  242. To digest a block of data such as a prototype certificate, an
  243. application calls R_DigestBlock, giving these arguments:
  244.  
  245.   -  a pointer to the block, and the block length
  246.   -  an integer identifying which message-digest algorithm to apply
  247.        (MD2 or MD5)
  248.  
  249. R_DigestBlock digests the block with the specified message-digest
  250. algorithm. It returns the message digest and the status of the
  251. operation.
  252.  
  253. ENCODED_CONTENT_LEN, DECODED_CONTENT_LEN, ENCRYPTED_CONTENT_LEN, and
  254. DECRYPTED_CONTENT_LEN are macros that assist in determining the
  255. maximum lengths of the results of cryptographic enhancements.
  256.  
  257.  
  258. R_SignPEMBlock
  259.  
  260. int R_SignPEMBlock (
  261.   unsigned char *encodedContent,                 /* encoded content */
  262.   unsigned int *encodedContentLen,     /* length of encoded content */
  263.   unsigned char *encodedSignature,             /* encoded signature */
  264.   unsigned int *encodedSignatureLen, /* length of encoded signature */
  265.   unsigned char *content,                                /* content */ 
  266.   unsigned int contentLen,                     /* length of content */ 
  267.   int recode,                                      /* recoding flag */
  268.   int digestAlgorithm,                  /* message-digest algorithm */
  269.   R_RSA_PRIVATE_KEY *privateKey         /* signer's RSA private key */
  270. );
  271.  
  272. R_SignPEMBlock computes a digital signature on content. Specifically,
  273. R_SignPEMBlock performs the following steps:
  274.  
  275.     1.    It digests content with digestAlgorithm, giving a message
  276.           digest.
  277.  
  278.     2.    It encrypts the message digest with privateKey, giving a
  279.           digital signature, and encodes the result in printable
  280.           ASCII according to RFC 1113, storing the encoding in
  281.           encodedSignature.
  282.  
  283.     3.    If recode is nonzero, it encodes content in printable ASCII,
  284.           storing the encoding in encodedContent.
  285.  
  286. If recode is nonzero, encodedContent will be an ASCII string, encoded
  287. according to RFC 1113. (It will not contain any line delimiters; the
  288. application must break the string into 64-character lines.)
  289. encodedContentLen will not be greater than
  290. ENCODED_CONTENT_LEN(contentLen). If recode is zero, encodedContent is
  291. ignored.
  292.  
  293. encodedSignature will be an ASCII string, encoded according to RFC
  294. 1113. encodedSignatureLen will not be greater than
  295. MAX_PEM_SIGNATURE_LEN.
  296.  
  297. digestAlgorithm is the algorithm by which the content is digested. It
  298. must be DA_MD2, which indicates the MD2 message-digest algorithm, or
  299. DA_MD5, which indicates the MD5 message-digest algorithm.
  300.  
  301. Return value:       0    success
  302.   RE_DIGEST_ALGORITHM    digestAlgorithm is invalid
  303.        RE_PRIVATE_KEY    privateKey cannot encrypt message digest
  304.  
  305.  
  306. R_VerifyPEMSignature
  307.  
  308. int R_VerifyPEMSignature (
  309.   unsigned char *content,                                /* content */ 
  310.   unsigned int *contentLen,                    /* length of content */ 
  311.   unsigned char *encodedContent,      /* (possibly) encoded content */
  312.   unsigned int encodedContentLen,      /* length of encoded content */
  313.   unsigned char *encodedSignature,             /* encoded signature */
  314.   unsigned int encodedSignatureLen,  /* length of encoded signature */
  315.   int recode,                                      /* recoding flag */
  316.   int digestAlgorithm,                  /* message-digest algorithm */
  317.   R_RSA_PUBLIC_KEY *publicKey            /* signer's RSA public key */
  318. );
  319.  
  320. R_VerifyPEMSignature verifies a digital signature on a message. Its
  321. operation is the inverse of R_SignPEMBlock. R_VerifyPEMSignature
  322. operates on encodedSignature and encodedContent. If recode is
  323. nonzero, it first decodes encodedContent according to RFC 1113, and
  324. stores the result in content. If recode is zero, content is ignored.
  325.  
  326. If recode is nonzero, contentLen will not be greater than
  327. DECODED_CONTENT_LEN(encodedContentLen).
  328.  
  329. Return value:       0    success
  330.   RE_CONTENT_ENCODING    encodedContent has RFC 1113 encoding error
  331. RE_SIGNATURE_ENCODING    encodedSignature has RFC 1113 encoding error
  332.   RE_DIGEST_ALGORITHM    digestAlgorithm is invalid
  333.         RE_PUBLIC_KEY    publicKey cannot decrypt signature
  334.          RE_SIGNATURE    signature on content is incorrect
  335.  
  336.  
  337. R_VerifyBlockSignature
  338.  
  339. int R_VerifyBlockSignature (
  340.   unsigned char *block,                                    /* block */
  341.   unsigned int blockLen,                         /* length of block */
  342.   unsigned char *signature,                            /* signature */  
  343.   unsigned int signatureLen,                 /* length of signature */
  344.   int digestAlgorithm,                  /* message-digest algorithm */
  345.   R_RSA_PUBLIC_KEY *publicKey            /* signer's RSA public key */
  346. );
  347.  
  348. R_VerifyBlockSignature verifies a digital signature on a block of
  349. data such as a certificate. Its operation is similar to
  350. R_VerifyPEMSignature, except that the block and signature are
  351. arbitrary byte strings, rather than RFC 1113-encoded strings.
  352.  
  353. Return value:       0    success
  354.   RE_DIGEST_ALGORITHM    digestAlgorithm is invalid
  355.         RE_PUBLIC_KEY    publicKey cannot decrypt signature
  356.          RE_SIGNATURE    signature on block is incorrect
  357.  
  358.  
  359. R_SealPEMBlock
  360.  
  361. int R_SealPEMBlock (
  362.   unsigned char *encryptedContent,    /* encoded, encrypted content */
  363.   unsigned int *encryptedContentLen,
  364.                             /* length of encoded, encrypted content */
  365.   unsigned char *encryptedKey,        /* encoded, encrypted DES key */  
  366.   unsigned int *encryptedKeyLen,
  367.                             /* length of encoded, encrypted DES key */  
  368.   unsigned char *encryptedSignature,/* encoded, encrypted signature */
  369.   unsigned int *encryptedSignatureLen,
  370.                           /* length of encoded, encrypted signature */
  371.   unsigned char iv[8],                   /* DES initializing vector */
  372.   unsigned char *content,                                /* content */
  373.   unsigned int contentLen,                     /* length of content */
  374.   int digestAlgorithm,                  /* message-digest algorithm */
  375.   R_RSA_PUBLIC_KEY *publicKey,        /* recipient's RSA public key */
  376.   R_RSA_PRIVATE_KEY *privateKey,        /* signer's RSA private key */
  377.   R_RANDOM_STRUCT *randomStruct                 /* random structure */
  378. );
  379.  
  380. R_SealPEMBlock computes a digital signature on content then encrypts
  381. the content and the signature. Specifically, R_SealPEMBlock performs
  382. the following steps:
  383.  
  384.     1.    It digests content with digestAlgorithm, giving a message
  385.           digest.
  386.  
  387.     2.    It encrypts the message digest with privateKey, giving a
  388.           digital signature.
  389.  
  390.     3.    It generates a random DES key and initializing vector,
  391.           storing the initializing vector in iv.
  392.  
  393.     4.    It encrypts content with the DES key and initializing vector
  394.           in cipher-block chaining mode, and encodes the result in
  395.           printable ASCII according to RFC 1113, storing the encoding
  396.           in encryptedContent.
  397.  
  398.     5.    It encrypts the DES key with publicKey and encodes the
  399.           result in printable ASCII, storing the encoding in
  400.           encryptedKey.
  401.  
  402.     6.    It encrypts the digital signature with the DES key and
  403.           initializing vector, and encodes the result in printable
  404.           ASCII, storing the encoding in encryptedSignature.
  405.  
  406. encryptedContent will be an ASCII string, encoded according to RFC
  407. 1113. (It will not contain any line delimiters; the application must
  408. break the string into 64-character lines.) encryptedContentLen will
  409. not be greater than ENCRYPTED_CONTENT_LEN(contentLen).
  410.  
  411. encryptedKey and encryptedSignature will be ASCII strings, encoded
  412. according to RFC 1113. encryptedKeyLen will not be greater than
  413. MAX_PEM_ENCRYPTED_KEY_LEN. encryptedSignatureLen will not be greater
  414. than MAX_PEM_ENCRYPTED_SIGNATURE_LEN.
  415.  
  416. digestAlgorithm is the algorithm by which the content is digested. It
  417. must be DA_MD2, which indicates the MD2 message-digest algorithm, or
  418. DA_MD5, which indicates the MD5 message-digest algorithm.
  419.  
  420. randomStruct must have been seeded.
  421.  
  422. Return value:       0    success
  423.   RE_DIGEST_ALGORITHM    digestAlgorithm is invalid
  424.        RE_PRIVATE_KEY    privateKey cannot encrypt message digest
  425.         RE_PUBLIC_KEY    publicKey cannot encrypt DES key
  426.        RE_NEED_RANDOM    randomStruct is not seeded
  427.  
  428.  
  429. R_OpenPEMBlock
  430.  
  431. int R_OpenPEMBlock (
  432.   unsigned char *content,                                /* content */
  433.   unsigned int *contentLen,                    /* length of content */
  434.   unsigned char *encryptedContent,    /* encoded, encrypted content */
  435.   unsigned int encryptedContentLen,
  436.                             /* length of encoded, encrypted content */
  437.   unsigned char *encryptedKey,        /* encoded, encrypted DES key */  
  438.   unsigned int encryptedKeyLen,
  439.                             /* length of encoded, encrypted DES key */  
  440.   unsigned char *encryptedSignature,/* encoded, encrypted signature */
  441.   unsigned int encryptedSignatureLen,
  442.                           /* length of encoded, encrypted signature */
  443.   unsigned char iv[8],                   /* DES initializing vector */
  444.   int digestAlgorithm,                  /* message-digest algorithm */
  445.   R_RSA_PRIVATE_KEY *privateKey,     /* recipient's RSA private key */
  446.   R_RSA_PUBLIC_KEY *publicKey            /* signer's RSA public key */
  447. );
  448.  
  449. R_OpenPEMBlock decrypts an encrypted message and verifies a digital
  450. signature. Its operation is the inverse of R_SealPEMBlock.
  451.  
  452. contentLen will not be greater than
  453. DECRYPTED_CONTENT_LEN(encryptedContentLen).
  454.  
  455. Return value:       0    success
  456.   RE_CONTENT_ENCODING    encryptedContent has RFC 1113 encoding error
  457.       RE_KEY_ENCODING    encryptedKey has RFC 1113 encoding error
  458. RE_SIGNATURE_ENCODING    encryptedSignature has RFC 1113 encoding
  459.                            error
  460.         RE_PUBLIC_KEY    publicKey cannot decrypt signature
  461.        RE_PRIVATE_KEY    privateKey cannot decrypt encrypted key
  462.                RE_KEY    recovered DES key cannot decrypt encrypted
  463.                            content or encrypted signature
  464.   RE_DIGEST_ALGORITHM    digestAlgorithm is invalid
  465.          RE_SIGNATURE    signature on content is incorrect
  466.  
  467.  
  468. R_DigestBlock
  469.  
  470. int R_DigestBlock (
  471.   unsigned char *digest,                          /* message digest */
  472.   unsigned int *digestLen,              /* length of message digest */ 
  473.   unsigned char *content,                                /* content */
  474.   unsigned int contentLen,                     /* length of content */
  475.   int digestAlgorithm                   /* message-digest algorithm */
  476. );
  477.  
  478. R_DigestBlock computes a message digest on content, storing the
  479. resulting message digest in digest and its length in digestLen.
  480.  
  481. digestAlgorithm is the algorithm by which the content is digested. It
  482. must be DA_MD2, which indicates the MD2 message-digest algorithm, or
  483. DA_MD5, which indicates the MD5 message-digest algorithm.
  484.  
  485. digestLen will not be greater than MAX_DIGEST_LEN.
  486.  
  487. Return value:       0    success
  488.   RE_DIGEST_ALGORITHM    digestAlgorithm is invalid
  489.  
  490.  
  491. KEY-PAIR GENERATION
  492.  
  493. RSAREF generates key pairs with the procedure R_GeneratePEMKeys.
  494. R_GeneratePEMKeys is typically called by key generation applications.
  495. To generate a new key pair, an application calls R_GeneratePEMKeys,
  496. giving the length of the modulus, the choice of exponent (F4 or F0),
  497. and a random structure. R_GeneratePEMKeys generates an RSA key pair
  498. and returns the status of the operation.
  499.  
  500.  
  501. R_GeneratePEMKeys
  502.  
  503. int R_GeneratePEMKeys (
  504.   R_RSA_PUBLIC_KEY *publicKey,                /* new RSA public key */
  505.   R_RSA_PRIVATE_KEY *privateKey,             /* new RSA private key */
  506.   R_RSA_PROTO_KEY *protoKey,                   /* RSA prototype key */
  507.   R_RANDOM_STRUCT *randomStruct                 /* random structure */
  508. );
  509.  
  510. R_GeneratePEMKeys generates a random RSA key pair, storing the
  511. resulting RSA public key in publicKey and the resulting RSA private
  512. key in privateKey.
  513.  
  514. Other parameters are as follows:
  515.  
  516.              protoKey    The RSA prototype key specifying the length
  517.                            in bits of the RSA modulus and the public
  518.                            exponent. (See Appendix B.)
  519.  
  520.          randomStruct    Random structure from which the key pair is
  521.                            derived. It must have been seeded.
  522.  
  523. Return value:       0    success
  524.        RE_MODULUS_LEN    modulus length invalid
  525.        RE_NEED_RANDOM    randomStruct is not seeded
  526.  
  527.  
  528. RUN-TIME LIBRARY
  529.  
  530. RSAREF operates on memory blocks with three platform-specific library
  531. procedures that are modeled after conventional C library functions:
  532.  
  533.              R_memcmp    compares two blocks of memory
  534.              R_memcpy    copies a block of memory
  535.              R_memset    sets a block of memory to a given value
  536.  
  537. These procedures can be found in the file 'r_stdlib.c'.
  538.  
  539.  
  540. R_memcmp
  541.  
  542. int R_memcmp (
  543.   POINTER firstBlock,                                /* first block */
  544.   POINTER secondBlock,                              /* second block */
  545.   unsigned int len                              /* length of blocks */
  546. );
  547.  
  548. R_memcmp compares the first len bytes of firstBlock and secondBlock.
  549. The value of len can be zero, in which case firstBlock and secondBlock
  550. are undefined and R_memcmp returns 0. R_memcmp compares the blocks by
  551. scanning the blocks from lowest address to highest until a difference
  552. is found. The smaller-valued block is the one with the smaller-valued
  553. byte at the point of difference. If no difference is found, the
  554. blocks are equal.
  555.  
  556. Return value:     < 0    firstBlock is smaller
  557.                   0      blocks are equal
  558.                   > 0    firstBlock is larger
  559.  
  560.  
  561. R_memcpy
  562.  
  563. void R_memcpy (
  564.   POINTER output,                                   /* output block */
  565.   POINTER input,                                     /* input block */
  566.   unsigned int len                              /* length of blocks */
  567. );
  568.  
  569. R_memcpy copies the first len bytes of input to output. The value of
  570. len can be zero, in which output and input are undefined. The blocks
  571. do not overlap.
  572.  
  573. No return value.
  574.  
  575.  
  576. R_memset
  577.  
  578. void R_memset (
  579.   POINTER output,                                   /* output block */
  580.   int value,                                               /* value */
  581.   unsigned int len                               /* length of block */
  582. );
  583.  
  584. R_memset sets the first len bytes of output to value. The value of
  585. len is zero, in which case output is undefined.
  586.  
  587. No return value.
  588.  
  589.  
  590. APPENDIX A: RSAREF ERROR TYPES
  591.  
  592. This appendix lists RSAREF's error types.
  593.  
  594.   RE_CONTENT_ENCODING    content or encrypted content has RFC 1113
  595.                            encoding error
  596.  
  597.   RE_DIGEST_ALGORITHM    message-digest algorithm is invalid
  598.  
  599.                RE_KEY    recovered DES key cannot decrypt encrypted
  600.                            content or encrypted signature
  601.  
  602.       RE_KEY_ENCODING    encrypted key has RFC 1113 encoding error
  603.  
  604.        RE_MODULUS_LEN    modulus length is invalid
  605.  
  606.        RE_NEED_RANDOM    random structure is not seeded
  607.  
  608.        RE_PRIVATE_KEY    private key cannot encrypt message digest,
  609.                            or cannot decrypt encrypted key
  610.  
  611.         RE_PUBLIC_KEY    public key cannot encrypt DES key, or cannot
  612.                            decrypt signature
  613.  
  614.          RE_SIGNATURE    signature on content or block is incorrect
  615.  
  616. RE_SIGNATURE_ENCODING    signature or encrypted signature has RFC 1113
  617.                            encoding error
  618.  
  619.  
  620. APPENDIX B: RSAREF TYPES
  621.  
  622. This appendix lists three RSAREF types: R_RSA_PUBLIC_KEY,
  623. R_RSA_PRIVATE_KEY, and R_RSA_PROTO_KEY.
  624.  
  625.  
  626. R_RSA_PUBLIC_KEY
  627.  
  628. typedef struct {
  629.   unsigned int bits;                   /* length in bits of modulus */
  630.   unsigned char modulus[MAX_RSA_MODULUS_LEN];            /* modulus */
  631.   unsigned char exponent[MAX_RSA_MODULUS_LEN];   /* public exponent */
  632. } R_RSA_PUBLIC_KEY;
  633.  
  634. An R_RSA_PUBLIC_KEY value is a structure specifying an RSA public key.
  635. There are three fields:
  636.  
  637.                 bits     length in bits of the modulus (not less than
  638.                            MIN_RSA_MODULUS_BITS and not greater than
  639.                            MAX_RSA_MODULUS_BITS)
  640.  
  641.              modulus     modulus n, represented as a
  642.                            MAX_RSA_MODULUS_LEN-byte number, most
  643.                            significant byte first, as many leading zero
  644.                            bytes as necessary
  645.  
  646.             exponent     public exponent e, represented like modulus
  647.  
  648.  
  649. R_RSA_PRIVATE_KEY
  650.  
  651. typedef struct {
  652.   unsigned int bits;                   /* length in bits of modulus */
  653.   unsigned char modulus[MAX_RSA_MODULUS_LEN];            /* modulus */
  654.   unsigned char publicExponent[MAX_RSA_MODULUS_LEN];
  655.                                                  /* public exponent */
  656.   unsigned char exponent[MAX_RSA_MODULUS_LEN];  /* private exponent */
  657.   unsigned char prime[2][MAX_RSA_PRIME_LEN];       /* prime factors */
  658.   unsigned char primeExponent[2][MAX_RSA_PRIME_LEN];
  659.                                                /* exponents for CRT */
  660.   unsigned char coefficient[MAX_RSA_PRIME_LEN];  /* CRT coefficient */
  661. } R_RSA_PRIVATE_KEY;
  662.  
  663. An R_RSA_PRIVATE_KEY value is a structure specifying an RSA private
  664. key. There are seven fields:
  665.  
  666.                 bits     length in bits of the modulus (not less than
  667.                            MIN_RSA_MODULUS_BITS and not greater than
  668.                            MAX_RSA_MODULUS_BITS)
  669.  
  670.              modulus     modulus n, represented as a
  671.                            MAX_RSA_MODULUS_LEN-byte number, most
  672.                            significant byte first, as many leading zero
  673.                            bytes as necessary
  674.  
  675.       publicExponent     public exponent e, represented like modulus
  676.  
  677.             exponent     private exponent d, represented like modulus
  678.  
  679.                prime     prime factors p and q of modulus, each
  680.                            represented as MAX_RSA_PRIME_LEN-byte
  681.                            numbers, most significant byte first, as
  682.                            many leading zero bytes as necessary, where
  683.                            p > q
  684.  
  685.       primeExponents     exponents (d mod p-1) and (d mod q-1) for
  686.                            Chinese remainder theorem (CRT) operations,
  687.                            each represented like prime factors
  688.  
  689.          coefficient     coefficient (q^{-1} mod p) for Chinese
  690.                            remainder theorem operations, represented
  691.                            like prime factors
  692.  
  693.  
  694. R_RSA_PROTO_KEY
  695.  
  696. /* RSA prototype key.
  697.  */
  698. typedef struct {
  699.   unsigned int bits;                   /* length in bits of modulus */
  700.   int useFermat4;                /* public exponent (1 = F4, 0 = 3) */
  701. } R_RSA_PROTO_KEY;
  702.  
  703. An R_RSA_PROTO_KEY value is a structure specifying the length in bits
  704. of the RSA modulus and the public exponent for key-pair generation.
  705. There are two fields:
  706.  
  707.                 bits     length in bits of the modulus (not less than
  708.                            MIN_RSA_MODULUS_BITS and not greater than
  709.                            MAX_RSA_MODULUS_BITS)
  710.  
  711.           useFermat4     a flag specifying the public exponent. If
  712.                            nonzero, it specifies F4 (65537); if 0, F0
  713.                            (3)
  714.  
  715.  
  716. APPENDIX C: PLATFORM-SPECIFIC TYPES AND CONSTANTS
  717.  
  718. This appendix lists three platform-specific types and one #define'd
  719. constant.
  720.  
  721.  
  722. TYPES
  723.  
  724. RSAREF requires three platform-specific types: POINTER, UINT2, and
  725. UINT4. These are defined in the file 'global.h'.
  726.  
  727.  
  728. POINTER
  729.  
  730. A POINTER value is a generic pointer to memory to which any other
  731. pointer can be cast.
  732.  
  733. Example:
  734.  
  735.     typedef unsigned char *POINTER;
  736.  
  737.  
  738. UINT2
  739.  
  740. A UINT2 value is a 16-bit unsigned integer.
  741.  
  742. Example:
  743.  
  744.     typedef unsigned short int UINT2;
  745.  
  746.  
  747. UINT4
  748.  
  749. A UINT4 value is a 32-bit unsigned integer.
  750.  
  751. Example:
  752.  
  753.     typedef unsigned long int UINT4;
  754.  
  755.  
  756. #DEFINE'D CONSTANTS
  757.  
  758. RSAREF requires one #define'd constant: PROTOTYPES. This is defined
  759. in the 'makefile' on the C compiler command line.
  760.  
  761. PROTOTYPES indicates the form that C function declarations are to
  762. take. If PROTOTYPES is nonzero, declarations take the form
  763.  
  764.     type function (type, ..., type);
  765.  
  766. Otherwise declarations take the form
  767.  
  768.     type function ();
  769.  
  770.  
  771. REFERENCES
  772.  
  773. [1]  J. Linn. RFC 1113: Privacy Enhancement for Internet Electronic
  774.      Mail: Part I -- Message Encipherment and Authentication
  775.      Procedures. Internet Activities Board, August 1989.
  776.  
  777. [2]  S. Kent and J. Linn. RFC 1114: Privacy Enhancement for Internet
  778.      Electronic Mail: Part II -- Certificate-Based Key Management.
  779.      Internet Activities Board, August 1989.
  780.  
  781. [3]  J. Linn. RFC 1115: Privacy Enhancement for Internet Electronic
  782.      Mail: Part III -- Algorithms, Modes, and Identifiers. Internet
  783.      Activities Board, August 1989.
  784.  
  785. [4]  RSA Data Security, Inc. PKCS #1: RSA Encryption Standard. Version
  786.      1.4, June 1991. Also published as NIST/OSI Implementors Workshop
  787.      SEC-SIG-91-18, June 1991. (Available by anonymous FTP from
  788.      'rsa.com' as 'pub/pkcs/pkcs-1.ps'.)
  789.  
  790. [5]  B.S. Kaliski Jr. The MD2 Message-Digest Algorithm. July 1, 1991.
  791.      (Available by anonymous FTP from 'rsa.com' as 'pub/md2.doc'.)
  792.  
  793. [6]  Ronald L. Rivest. The MD5 Message-Digest Algorithm. In
  794.      preparation. (Earlier version available by anonymous FTP from
  795.      'rsa.com' as 'pub/md5.doc'.)
  796.  
  797. [7]  National Bureau of Standards. FIPS Publication 46-1: Data
  798.      Encryption Standard. January 1988.
  799.  
  800. [8]  National Bureau of Standards. FIPS Publication 81: DES Modes of
  801.      Operation. December 1980.
  802.  
  803. [9]  B.S. Kaliski Jr. Privacy Enhancement for Internet Electronic
  804.      Mail: Part IV: Notary, Co-Issuer, CRL-Storing, and
  805.      CRL-Retrieving Services. Draft, July 1, 1991. (Available by
  806.      anonymous FTP from 'rsa.com' as 'pub/forms.doc'.)
  807.